﻿#region File and License Information
/*
<File>
	<Copyright>Copyright © 2009, Daniel Vaughan. All rights reserved.</Copyright>
	<License>
	This file is part of Daniel Vaughan's base library

    Daniel Vaughan's base library is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Daniel Vaughan's base library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with Daniel Vaughan's base library.  If not, see http://www.gnu.org/licenses/.
	</License>
	<Owner Name="Daniel Vaughan" Email="dbvaughan@gmail.com"/>
	<CreationDate>2010-01-23 17:21:10Z</CreationDate>
</File>
*/
#endregion
using System;

namespace DanielVaughan.Services
{
	/// <summary>
	/// Indicates the result of SetSetting call in the <see cref="ISettingsService"/>.
	/// </summary>
	public enum SetSettingResult
	{
		/// <summary>
		/// The setting was changed.
		/// </summary>
		Successful,
		/// <summary>
		/// Occurs when a subscriber to the SettingChangedEvent cancels the change.
		/// </summary>
		Cancelled
	}

	/// <summary>
	/// This service allow settings to be saved at runtime.
	/// </summary>
	public interface ISettingsService
	{
		/// <summary>
		/// Gets the setting instance with the specified key that is of the specified type.
		/// If no entity has been saved, then the specified default value is returned.
		/// </summary>
		/// <typeparam name="TSetting">The type of the setting.</typeparam>
		/// <param name="key">The key.</param>
		/// <param name="defaultValue">The default value.</param>
		/// <returns>The located setting, or the default value if <code>null</code>.</returns>
		TSetting GetSetting<TSetting>(string key, TSetting defaultValue);

		/// <summary>
		/// Gets the setting instance with the specified key that is of the specified type.
		/// If no entity has been saved, then the specified default value is returned.
		/// </summary>
		/// <param name="key">The setting key.</param>
		/// <param name="defaultValue">The default value.</param>
		/// <returns>The located setting, or the default value if <code>null</code>.</returns>
		object GetSetting(string key, Type settingType, object defaultValue);

		/// <summary>
		/// Records the setting using the specified key as a unique identifier.
		/// </summary>
		/// <param name="key">The key.</param>
		/// <param name="value">The value.</param>
		/// <returns><code>Successful</code> if the setting was correctly stored,
		/// <code>Cancelled</code> if a listener intervened an prevented cancelled the setting.</returns>
		SetSettingResult SetSetting(string key, object value);

		/// <summary>
		/// Clears all settings.
		/// </summary>
		void ClearSettings();

		/// <summary>
		/// Occurs when a setting is changed.
		/// </summary>
		event EventHandler<SettingChangeEventArgs> SettingChanged;

		/// <summary>
		/// Occurs when a setting is about to change.
		/// </summary>
		event EventHandler<SettingChangingEventArgs> SettingChanging;
	}
}
